 READ_LOC.TXT           Advantage Local Server               7.0
==============         ========================         =============

This READ_LOC.TXT file contains information about the Advantage Local
Server.


Contents:
==========
1. Effects of Upgrading
2. Effects of Upgrading from a Version Prior to v6.2
3. Important Notes
4. What's New in v7.0
5. Advantage TDataSet Descendant Notes
6. Advantage ODBC Driver Notes
7. Advantage OLE DB Provider Notes
8. Advantage Client Engine API Notes
9. CA-Visual Objects RDD Notes

1. Effects of Upgrading
========================

The following Advantage functionality changes may affect your
applications if you upgrade to version 7.0 of the Advantage
Local Server.

a) As of v7.0, the maximum user group name length in a data dictionary
   is limited to 100 characters. In versions prior to 7.0, the limit
   was 200 characters.

b) If issuing SQL UPDATE or INSERT statements, there are DBF numeric
   fields involved in the update/insert, and the values specified for
   the numeric fields have more precision (decimal digits) than the
   numeric field definition, the v7.0 SQL engine no longer truncates
   the extra decimal digits while returning a data truncation error
   (Native Error 2102). Instead with v7.0, the value is rounded and
   truncated using the standard method (5 and above are rounded up)
   and no error is returned.

c) In v7.0, SQL support was added for scripts of semicolon delimited
   SQL statements. For applications that build SQL statements
   dynamically and allow user input to affect the statement that is
   generated, this can generate some security issues. Since old
   (pre-7.0) clients can be used with a 7.0 server, the installing of
   the new 7.0 server brings these new security risks. See the
   "Scripts" topic in the "Advantage SQL" | "Supported Grammar" book in
   the Advantage Help file for details.

d) In versions prior to 7.0, a bug let users add views that had ORDER
   BY clauses. A view cannot have an ORDER BY clause. This bug has been
   fixed, so creating views with an ORDER BY clause is no longer
   allowed. Existing views will continue to work, but if you try to add
   a new view, or modify an existing view that has an ORDER BY clause,
   the operation will fail.

e) In versions prior to 7.0, when executing stored procedures, the
   current user's access rights to tables or views were checked when
   tables or views were used in the stored procedures. An access
   permission error was returned if current user did not have
   sufficient access to tables or views used in the stored procedure.
   This behavior was inconsistent with the industry standard. Advantage
   v7.0 will no longer check current user's access rights to tables or
   views when they are used in the stored procedure.

f) DBF tables with memo or blob fields that are newly encrypted (where
   all records in the table are encrypted) using a 7.0 server and
   client will not be backwards compatible with pre-7.0 clients and
   servers because memo and blob data in DBF tables get encrypted in
   Advantage 7.0.


2. Effects of Upgrading from a Version Prior to v6.2
=====================================================

In addition to the effects of upgrading from version 6.2 of the
Advantage Local Server mentioned in the section above, the
following Advantage functionality changes may affect your applications
if you upgrade to version 7.0 of the Advantage Local Server from a
version of the Advantage Local Server prior to v6.2.

a) The Advantage Expression Engine will now return a 3?01 error if a
   record filter or index expression contains an extra comma or right
   paren and has any other characters following that extra character.
   For example, the following expressions are now illegal: "lastname ,
   firstname", "left( 'extra paren', 10 ))", and "lastname, Advantage
   rules baby". Prior to v6.2, those expressions would have not
   returned an error and everything after the comma or right paren
   would have been ignored. Any existing applications that are
   mistakenly using a bad expression may start getting 3?01 errors if
   upgrading to v6.2 or greater.

b) Index creations will now return a 7089 error if they are cancelled.
   Prior to v6.2, a cancelled index creation would not cause the
   index creation operation to return an error. If your application
   provides index cancellation functionality you will need to address
   each instance and modify the source to correctly handle an error
   code (or exception if using the Advantage TDataSet Descendant) being
   returned from the index creation call.

c) When using the Advantage Local Server, the thread that calls and
   performs the user's registered callback function is the same thread
   that is actually performing the database operations (e.g., index
   creation and query execution). Because of this, it is important the
   application's registered callback function (via
   AdsRegisterCallbackFunction, AdsRegisterProgressCallback, or
   AdsRegisterSQLAbortFunc) be as efficient as possible. For example,
   the callback function should not block and wait for user input
   because that would stop the Advantage Local Server progress until
   the callback function returns. Prior to version 6.1, the callback
   function ran on a different thread so this was not an issue.

d) As of v6.1, the SQL scalar functions soundex() and difference()
   were updated to conform to the standard definition. The soundex()
   function now returns the expected 4 digit phonetic code of the
   form <letter><digit><digit><digit>. The difference() function now
   returns an integer value in the range 0 to 4, where 4 indicates
   the closest phonetic match, and 0 indicates little or no phonetic
   match.

e) The Advantage encryption in version 6.0 and greater of Advantage
   clients and servers uses a 160-bit encryption algorithm instead of
   the 40-bit encryption algorithm used in previous versions. Advantage
   version 6.0 and greater will also encrypt the memo and BLOB data in
   ADT tables if the table is completely encrypted. Because of these
   changes, if a table is encrypted with a password that is longer
   than 5 characters using Advantage version 6.0 or greater clients, or
   if a table is fully encrypted using Advantage version 6.0 or
   greater clients (regardless of the password length), the table is not
   backwards compatible with earlier versions (i.e., versions prior to
   6.0) of Advantage clients and servers. However, tables encrypted
   using earlier versions (i.e., versions prior to 6.0) of Advantage
   clients are fully compatible with Advantage version 6.0 and greater
   clients and servers.

f) Advantage Client Engine-based clients older than v2.5 will not be
   able to access encrypted tables with version 6.0 or greater of the
   Advantage Database Server. Use version 6.0 or greater Advantage
   Client Engine-based clients with an Advantage 6.0 or greater server.

g) Upgrading to version 6.0 or greater may affect Advantage applications
   that are implemented to attempt a connection to the Advantage Local
   Server if there is a problem connecting to the Advantage Database
   Server. In releases prior to v6.0, if the connection attempt
   to the Advantage Database Server failed for any reason whatsoever,
   the application would attempt to connect via the Advantage Local
   Server. This scheme was invalid for certain scenarios since the
   scaling to Local Server should ONLY occur if the Advantage Database
   Server is not available or cannot be communicated with. If the
   Advantage Database Server is available, but the connection fails for
   some other reason (with some 7000 error, for example), that error
   will now be returned to the application rather than the application
   attempting to connect via the Advantage Local Server. This will
   allow the developer to detect application or database problems that
   affect the connection to the Advantage Database Server that would
   normally succeed if not for the application/database problem(s).
   Only those errors that occur during the Advantage Database Server
   connection attempt that indicate the server is not available or
   cannot be communicated with (i.e., 6000 errors) will result in the
   scaling of the connection to the Advantage Local Server.

h) If you are upgrading from a version of the Advantage Local Server
   prior to v5.5, you must upgrade to version 2.5 or greater of the
   Advantage client if using ADT tables, and you must reindex your
   indexes if using ADI indexes. It is not necessary to upgrade and
   reindex if you are upgrading from version 5.5 or greater of the
   Advantage Local Server and/or are using DBF tables with CDX, IDX,
   or NTX indexes.

i) Encryption support within Advantage changed substantially in
   version 5.5 in order to improve security, performance, and data
   integrity. If you are using encryption in your application,
   and are upgrading from a version prior to v5.5, refer to the
   document "ENCRYPT.DOC" that is available for download from the
   Advantage Developer Zone web site <DevZone.AdvantageDatabase.com>.
   If you are upgrading from version 5.5 or greater, no issues related
   to encryption should affect you.


3. Important Notes
============================

a) The Advantage Local Server allows Advantage applications to access
   tables, index files, and memo files that are located on computers
   that are not running the Advantage Database Server. The Advantage
   Local Server does NOT provide a client/server solution in a
   networked environment like the Advantage Database Server does.
   Thus, the client/server benefits of drastically increased multi-user
   performance, integrity, and security, which are available with the
   Advantage Database Server client/server solution, are not available
   when using the Advantage Local Server in a networked environment.

b) By default, the only Advantage server types an Advantage application
   will attempt to connect to is the Advantage Database Server or the
   Advantage Internet Server. Thus, by default, an Advantage
   application will NOT attempt to connect to the Advantage Local
   Server, even if the connect is attempted on a PC on which the
   Advantage Database Server or Advantage Internet Server is not
   available. Refer to one of the Advantage client specific notes
   sections below to determine how to enable use of the Local Server
   for the desired Advantage client.

c) If the Advantage server types in which to connect are specified as
   "either" the Advantage Database Server or the Advantage Local
   Server, the Advantage application will first attempt to connect to
   the Advantage Database Server and then to the Advantage Local Server
   if the Advantage Database Server is not available. The very first
   connect attempt to the Advantage Database Server MAY TAKE UP TO TWO
   SECONDS TO TIME OUT if the Advantage Database Server is not
   available before automatically attempting to connect to the
   Advantage Local Server. Any further connection attempts to the
   Advantage Database Server for that server will fail immediately.
   The two second timeout will only occur if the Advantage Database
   Server is not present on the specified server AND if the Advantage
   remote communication DLL (AXCWS32.DLL) is located in the client PC's
   search path. If the Advantage remote communication DLL is NOT
   located in the client PC's search path, the timeout of the connect
   to the Advantage Database Server will be immediate.

d) Transaction Processing is not supported in the Advantage Local
   Server. Use of Advantage Transaction Processing functionality may
   appear to complete successfully, but in fact, use of Transaction
   Processing features will be ignored.

e) ADSLOCAL.CFG is the Advantage Local Server configuration file. The
   Advantage Local Server reads this configuration file when the library
   is loaded. Values input after the keyword and equal sign are used to
   configure the local server. If no value is inserted after a keyword
   and equal sign, the default is used. This file must be located in
   each client PC's current working directory or in it is search path
   (e.g. the \WINDOWS\SYSTEM directory in Windows, or the /etc
   directory in Linux).


4. What's New in v7.0
============================

a) New Advantage functionality specific to the Advantage Local Server:

   * Modified stored procedure access right checking to be consistent
     with the industry standard. Advantage v7.0 no longer checks the
     current user's access rights to tables or views when they are used
     in a stored procedure.

   * Added support for the Turkish OEM character set.

b) New Advantage functionality associated with the SQL engine:

   * Added ability to execute SQL scripts via a semicolon delimited
     list of SQL statements. Not only is executing scripts in this
     fashion convenient, it can also increase performance, as the
     statements are sent to the server in one request and processed
     individually by the server. In low bandwidth situations, or when
     executing a large script, this can result in a dramatic speed
     increase. See the "Scripts" topic in the "Advantage SQL" |
     "Supported Grammar" book in the Advantage Help file for details.

   * Added transaction syntax support. BEGIN TRANSACTION, COMMIT WORK,
     ROLLBACK WORK, and SET TRANSACTION statements are now supported.

   * Added database permission GRANT and REVOKE statements.

   * Added CREATE DATABASE and CREATE TRIGGER statements.

   * All data dictionary metadata is now accessible through SQL system
     tables and modifiable through system stored procedures. See the
     "Advantage SQL" | "System Views" book in the Advantage Help file
     for details.

   * Added CAST scalar for precision data type conversions.

   * Improved RAND scalar so that the number produced exhibits a
     better "random" behavior.

   * Added a virtual system table named iota. Iota is a table
     with one logical (SQL_BIT) column named "iota" and has a single
     row in the table with a NULL value in the "iota" column. The main
     purpose of the IOTA table is to provide an efficient method for
     evaluating an SQL expression on the server.

   * Improved performance of some SQL operations that require temporary
     sort files with larger data sets. For example, GROUP BY statement
     performance may be more than 10 times faster on data sets of 1
     million records and larger. In addition to GROUP BY statements,
     this can improve the speed of UNION, DISTINCT, and ORDER BY
     operations.

c) Miscellaneous new functionality:

   * Added a highly optimized Full Text Search engine. It is possible
     to search character, memo, and BLOB data using intuitive search
     phrases constructed of words and logical operators. See the "Full
     Text Search" topic in the Help file for details.

   * Added support for triggers. A trigger is a piece of code (similar
     to a stored procedure) that is executed on the server in response
     to an insert, update, or delete operation. Triggers can provide a
     very powerful means to maintain business rules at the database
     level.

   * Improved the performance of various database operations. For
     example, one should expect performance improvements of 10% and
     greater with insert/append operations, operations involving
     Advantage Optimized Filters, and deleting of records when the
     table contains one or more memo/BLOB fields.

   * When creating new indexes on a table with many records or when
     performing a reindex operation on a table with many records, the
     creation of that index will be much faster in 7.0 than earlier
     versions of Advantage Database Server. On tables with fewer than
     100,000 records, the performance improvement may not be
     significant. Tables with more than 100,000 records can expect up
     to a 50% performance increase. Table with multiple millions of
     records can expect even better performance increases, perhaps as
     much as 300% faster. Increasing the Advantage Database Server
     SORT_BUFFER configuration value can lead to even larger index
     creation performance increases with very large tables.

   * Added database (Advantage Data Dictionary) upgrade functionality.
     This functionality allows developers to ship version "A" of a
     database defined in a data dictionary, then later ship version "B"
     of the data dictionary. Functionality exists to compare Advantage
     Data Dictionaries and generate SQL upgrade scripts to "upgrade"
     one data dictionary to be structurally the same as a second data
     dictionary.

   * Added various Advantage Extended Procedure (AEP) Enhancements. A
     new AEP interface has been developed, which includes the following
     features:
      - AEP is passed an active connection handle, as opposed to a
        username and password. This active connection handle can be
        used to perform all data operations; no additional
        connections are required.
      - AEPs can be called inside a transaction, and all operations
        performed in the AEP using the active connection handle passed
        to the AEP are included in the context of the transaction.
      - Input and output parameters are passed through the virtual
        tables __input and __output. No more parsing of input/output
        table paths is necessary.
      - An additional connection to read the input and output tables
        is no longer necessary.
      - An in-memory table (__error) can be used to return
        descriptive error messages to the client application.
      - The number of rows affected can be returned and used from the
        client application just like it can with traditional SQL
        INSERT/UPDATE/DELETE statements.
      - New AEPs do not check user privileges when executing, which
        allows you to hide tables from the user(s), but allow access
        and modifications to those tables through AEPs that you
        control.
      - A combination of several of the above new features result in
        overall better AEP performance than with earlier versions.

   * Added new Money field data type for ADTs. This BCD-like field
     allows for currency data stored internally as a 64-bit integer,
     with 4 implied decimal digits from -922,337,203,685,477.5807 to
     +922,337,203,685,477.5807. No precision will be lost when doing
     calculations involving this data type.

   * Added support for DBF memo and BLOB data encryption. If all
     records in a DBF table are encrypted, all fields in the table will
     be encrypted, including and memo and binary fields.


5. Advantage TDataSet Descendant Notes
======================================

a) The Advantage TDataSet Descendant client supports accessing data via
   the Advantage Local Server. Use of the Advantage Local Server can be
   enabled via the TAdsConnection component as well as the TAdsSettings
   component. Using the TAdsConnection component is usually the easier
   way to enable use of the Advantage Local Server. To enable use of
   the Advantage Local Server via the TAdsConnection component, click on
   the Advantage tab. Then select the TAdsConnection component. Then
   select the AdsServerTypes property. Finally set the stADS_LOCAL
   sub-property to TRUE. The AdsServerTypes property allows you to
   specify which Advantage server type(s) to use when obtaining an
   Advantage server connection. The default AdsServerTypes setting is
   stADS_REMOTE set to FALSE, stADS_AIS set to FALSE, and stADS_LOCAL
   set to FALSE. If multiple AdsServerTypes sub-properties are set to
   TRUE, the application will attempt to connect to Advantage servers in
   the following order: stADS_REMOTE first (if set to TRUE), stADS_AIS
   next (if set to TRUE), and stADS_LOCAL last (if set to TRUE). If
   either the stADS_REMOTE connect or the stADS_AIS connect is
   successful, the stADS_LOCAL connect will never be attempted. Setting
   any TAdsConnection.AdsServerTypes subproperties will override any
   TAdsSettings.AdsServerTypes subproperties specified.

b) The AdsRightsCheck "True" mode will always be used when opening/
   creating a table with the Advantage Local Server no matter how the
   AdsRightsCheck sub-property (under the AdsTableOptions property in
   the TAdsTable component) is set.

c) The AdsLockType "Compatible" mode will always be used when
   opening/creating a table with the Advantage Local Server no matter
   how the AdsLockType sub-property (under the AdsTableOptions property
   in the TAdsTable component) is set.


6. Advantage ODBC Driver Notes
===============================

a) The Advantage ODBC Driver supports use of the Advantage Local
   Server. To enable use of the Advantage Local Server, open the ODBC
   administrator. Then select the Advantage data source you wish to
   allow use of the Advantage Local Server. Finally, click the
   "Setup" or "Configure" button, click the Options button, and check
   the box labeled "Local Server". By enabling the Local Server, any
   data files in the specified data source that exist on a PC without
   the Advantage Database Server running will use the Advantage Local
   Server instead.

b) The "Advantage Locking" mode used will always be "Compatible" when
   opening/creating a table with the Advantage Local Server no matter
   which setting is specified.


7. Advantage OLE DB Provider Notes
===================================

a) The Advantage OLE DB Provider supports use of the Advantage Local
   Server. Enabling use of the Advantage Local Server can be performed
   by using the Advantage ServerType property, which can be specified
   in the ADO connection string, in the OLE DB Provider String
   property, or via the ADSPROP_INIT_SERVER_TYPE property. Setting the
   property to "ADS_LOCAL_SERVER" enables use of the Advantage Local
   Server. The default Advantage ServerType property setting is
   "ADS_REMOTE_SERVER". If multiple Advantage server types are
   ORed together, the application will attempt to connect to Advantage
   servers in the following order: ADS_REMOTE_SERVER first (if
   specified) and ADS_LOCAL_SERVER last (if specified). If the
   ADS_REMOTE_SERVER connect is successful, the ADS_LOCAL_SERVER
   connect will never be attempted.

b) The SecurityMode ADS_CHECKRIGHTS will always be used when
   opening/creating a table with the Advantage Local Server no matter
   how the Advantage SecurityMode property is set.

c) The LockMode ADS_COMPATIBLE will always be used when opening/
   creating a table with the Advantage Local Server no matter how
   the Advantage LockMode property is set.


8. Advantage Client Engine API Notes
=====================================

a) The following are Advantage Client Engine APIs applicable for use
   with the Advantage Local Server:

   UNSIGNED32 AdsSetServerType( UNSIGNED16 usServerType )

      AdsSetServerType() allows you to specify which Advantage server
      types can be connected to. The available options are
      ADS_REMOTE_SERVER, ADS_AIS_SERVER, and ADS_LOCAL_SERVER. The
      default option is ADS_REMOTE_SERVER logically ORed with
      ADS_AIS_SERVER. This means that by default an Advantage Client
      Engine application will attempt to connect to the Advantage
      Database Server first, and then to the Advantage Internet Server
      if the Advantage Database Server is not available. If the
      ADS_LOCAL_SERVER option is logically ORed together with either
      or both of the other server type options, the Advantage Client
      Engine application will first attempt to connect to the Advantage
      Database Server and/or Advantage Internet Server and then to the
      Advantage Local Server if the Advantage Database Server and/or
      Advantage Internet Server are not available. The
      AdsSetServerType() setting is per thread for the Advantage
      Client Engine.

   UNSIGNED32 AdsConnect60( UNSIGNED8  *pucConnectPath,
                            UNSIGNED16 usServerTypes,
                            UNSIGNED8  *pucUserName,
                            UNSIGNED8  *pucPassword,
                            UNSIGNED32 ulOptions,
                            ADSHANDLE *phConnect );

      AdsConnect60() allows you to specify the usServerTypes directly
      in the connect API, making the above AdsSetServerType() API
      unnecessary. The usServerTypes parameter works exactly as
      described above.

   UNSIGNED32 AdsGetConnectionType( ADSHANDLE  hConnect,
                                    UNSIGNED16 *pusConnectType )

      AdsGetConnectionType() will return which Advantage server type
      is associated with the specified connection, either
      ADS_REMOTE_SERVER, ADS_AIS_SERVER, or ADS_LOCAL_SERVER.

b) The usCheckRights parameter (with options ADS_CHECKRIGHTS and
   ADS_IGNORERIGHTS) in the AdsOpenTable() and AdsCreateTable() APIs is
   ignored when opening/creating a table with the Advantage Local
   Server. The ADS_CHECKRIGHTS setting will always be used when
   opening or creating a table with the Advantage Local Server.

c) The usLockType parameter (with options ADS_PROPRIETARY_LOCKING and
   ADS_COMPATIBLE_LOCKING) in the AdsOpenTable() and AdsCreateTable()
   APIs is ignored when opening/creating a table with the Advantage
   Local Server. The ADS_COMPATIBLE_LOCKING setting will always be
   used when opening or creating a table with the Advantage Local
   Server.


9. CA-Visual Objects RDD Notes
==================================

a) The Advantage CA-Visual Objects RDD supports use of the Advantage
   Local Server via the AX_SetServerType() function. AX_SetServerType()
   takes three logical parameters: lUseRemoteServer,
   lUseInternetServer, and lUseLocalServer. To use the Advantage Local
   Server, pass a .T. value for the lUseLocalServer parameter. The
   default AX_SetServerType() parameter settings are lUseRemoteServer
   set to .T., lUseInternetServer set to .T., and lUseLocalServer set
   to .F. If multiple AX_SetServerType() parameters are set to .T.,
   the application will attempt to connect to Advantage servers in the
   following order:  Remote first (if set to .T.), AIS next (if set to
   .T.), and Local last (if set to .T.). If either the Remote connect
   or the AIS connect is successful, the Local connect will never be
   attempted.

b) The security mode set by the AX_RightsCheck() function with free
   tables will always be .T. with the Advantage Local Server. Even if
   .F. is passed to the AX_RightsCheck() function, the "rights
   checking" security mode will be used.

c) The locking mode set by the AX_AXSLocking() function will always be
   .F. with the Advantage Local Server. Even if .T. is passed to the
   AX_AXSLocking() function, the Advantage "compatibility" locking mode
   will be used.

